home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / UpVar.3 < prev    next >
Encoding:
Text File  |  1995-02-22  |  2.7 KB  |  77 lines
  1. '\"
  2. '\" Copyright (c) 1994 The Regents of the University of California.
  3. '\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) UpVar.3 1.3 95/02/22 14:37:22
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_UpVar tclc 7.4
  12. .BS
  13. .SH NAME
  14. Tcl_UpVar, Tcl_UpVar2 \- link one variable to another
  15. .SH SYNOPSIS
  16. .nf
  17. \fB#include <tcl.h>\fR
  18. .sp
  19. int
  20. \fBTcl_UpVar(\fIinterp, frameName, sourceName, destName, flags\fB)\fR
  21. .sp
  22. int
  23. \fBTcl_UpVar2(\fIinterp, frameName, name1, name2, destName, flags\fB)\fR
  24. .SH ARGUMENTS
  25. .AS Tcl_VarTraceProc prevClientData
  26. .AP Tcl_Interp *interp in
  27. Interpreter containing variables;  also used for error reporting.
  28. .AP char *frameName in
  29. Identifies the stack frame containing source variable.
  30. May have any of the forms accepted by
  31. the \fBupvar\fR command, such as \fB#0\fR or \fB1\fR.
  32. .AP char *sourceName in
  33. Name of source variable, in the frame given by \fIframeName\fR.
  34. May refer to a scalar variable or to an array variable with a
  35. parenthesized index.
  36. .AP char *destName in
  37. Name of destination variable, which is to be linked to source
  38. variable so that references to \fIdestName\fR
  39. refer to the other variable.  Must not currently exist except as
  40. an upvar-ed variable.
  41. .AP int flags in
  42. Either TCL_GLOBAL_ONLY or 0;  if non-zero, then \fIdestName\fR is
  43. a global variable;  otherwise it is a local to the current procedure
  44. (or global if no procedure is active).
  45. .AP char *name1 in
  46. First part of source variable's name (scalar name, or name of array
  47. without array index).
  48. .AP char *name2 in
  49. If source variable is an element of an array, gives the index of the element.
  50. For scalar source variables, is NULL.
  51. .BE
  52.  
  53. .SH DESCRIPTION
  54. .PP
  55. \fBTcl_UpVar\fR and \fBTcl_UpVar2\fR provide the same functionality
  56. as the \fBupvar\fR command:  they make a link from a source variable
  57. to a destination variable, so that references to the destination are
  58. passed transparently through to the source.
  59. The name of the source variable may be specified either as a single
  60. string such as \fBxyx\fR or \fBa(24)\fR (by calling \fBTcl_UpVar\fR)
  61. or in two parts where the array name has been separated from the
  62. element name (by calling \fBTcl_UpVar2\fR).
  63. The destination variable name is specified in a single string;  it
  64. may not be an array element.
  65. .PP
  66. Both procedures return either TCL_OK or TCL_ERROR, and they
  67. leave an error message in \fIinterp->result\fR if an error
  68. occurs.
  69. .PP
  70. As with the \fBupvar\fR command, the source variable need not exist;
  71. if it does exist, unsetting it later does not destroy the link.  The
  72. destination variable may exist at the time of the call, but if so
  73. it must exist as a linked variable.
  74.  
  75. .SH KEYWORDS
  76. linked variable, upvar, variable
  77.